Các API của luồng cập nhật thông tin

• Tài liệu này mô tả các API của luồng cập nhật thông tin (hay còn gọi là luồng eKYC) của hệ thống FPT AI eKYC. Các API của luồng này bao gồm:

  • API khởi tạo phiên
  • API OCR
  • API kiểm tra liveness và so khớp khuôn mặt
  • API kiểm tra data NFC
  • API nhận thông tin QR Code

• Base URL

  • Môi trường Staging: https://api.fpt.ai/vision/ekyc/be-stag

  • Môi trường Production: https://api.fpt.ai/vision/ekyc-be

• Sơ đồ tuần tự gọi các API trong luồng cập nhật thông tin

1. API khởi tạo phiên

1.1. Request Url

POST base_url/session/init

Nếu sử dụng FPT AI eKYC SDK, bạn sử dụng URL sau:

POST base_url/init_session

1.2. Request Headers

Tham số	Yêu cầu	Giá trị mặc định	Mô tả
api-key	Có		API key để sử dụng hệ thống FPT AI eKYC
client_uuid	Không		UUID sinh ra từ hệ thống của khách hàng để tự quản lý phiên eKYC
device-type	Có		Thiết bị đang sử dụng, các giá trị cho phép bao gồm: android ios web-sdk
only-engine	Không		Đặt giá trị bằng 1 khi sử dụng luồng chỉ OCR
sdk-version	Không	String	Phiên bản của FPT AI eKYC SDK. Nên sử dụng tham số này để đảm bảo hiệu quả khi sử dụng SDK

1.3. Mẫu request

curl --location --request POST 'base_url/session/init' \
--header 'api-key: your-api-key' \
--header 'device-type: android' \
--header 'client_uuid: your-uuid'

1.4. Response

1.4.1. Mẫu response

• Thành công: http_code = 200

{
    "code": "200",
    "message": "success",
    "session-id": "7760a743-884b-4195-b781-892e72c7b0b6",
}

• Thất bại: http_code != 200

1.4.2. Mô tả response

Tham số	Loại dữ liệu	Mô tả	Ghi chú
code	string	Mã trạng thái trả về của yêu cầu	200: Thành công
message	string	Thông báo lỗi trả về (nếu có)	200: Thành công 401: Lỗi xác thực 403: Lỗi dùng sai session-id 504: Lỗi kết nối hệ thống 500: Lỗi server hệ thống
session-id	string	Mã ID duy nhất của phiên eKYC được sinh ra bởi eKYC Backend. session-id sau đó phải được gửi kèm trong headers của tất cả các request trong cùng phiên

2. API OCR

2.1. Request Url

POST base_url/ocr

2.2. Request Headers

Tham số	Yêu cầu	Loại dữ liệu	Mô tả	Chú ý
session-id	Có	String	ID duy nhất của phiên eKYC nhận được từ bước khởi tạo phiên
api-key	Có	String	API key để sử dụng hệ thống FPT AI eKYC
device-type	Có	String	Thiết bị đang sử dụng, các giá trị cho phép bao gồm: android ios web-sdk
document-type	Có	String	Loại giấy tờ sử dụng. Có 3 loại được hỗ trợ: Căn cước công dân/Chứng minh nhân dân: idr Hộ chiếu: passport Giấy phép lái xe: dlr
side-type	Không	String	Tùy chọn này dành cho trường hợp client muốn gửi từng mặt của giấy tờ lên server eKYC để xử lý ngay sau khi chụp, thay vì đợi chụp đủ cả hai mặt. Các giá trị bao gồm: front (mặt trước) back (mặt sau) Lưu ý rằng ảnh mặt trước phải được gửi trước.
lang	Không	String	Ngôn ngữ sử dụng, các giá trị cho phép bao gồm: en vi	mặc định: en
get-detail-response	Không	String	Bao gồm dữ liệu thô của mô hình AI trong kết quả trả về (trong trường detail_response).	Giá trị 1: Bao gồm dữ liệu đầu ra thô của mô hình AI trong phản hồi Nếu đặt thành bất kỳ giá trị nào khác hoặc nếu header này không được cung cấp, dữ liệu thô sẽ không được trả
sdk-version	Không	String	Phiên bản của FPT AI eKYC SDK. Nên sử dụng tham số này để đảm bảo hiệu quả khi sử dụng SDK

2.3. Request Body

FormData chứa các ảnh cho truy vấn. Ảnh mặt trước phải được cung cấp trước ảnh mặt sau. Nếu document-type là passport hoặc sử dụng side-type trong headers, khách hàng chỉ cung cấp 1 ảnh cho hệ thống trong mỗi request.

Tham số	Yêu cầu	Giá trị mặc định	Mô tả
files	Có	File ảnh	Ảnh chụp mặt trước của giấy tờ
files	Có	File ảnh	Ảnh chụp mặt sau của giấy tờ

2.4. Mẫu request

curl --location --request POST 'base_url/ocr' \
--header 'api-key: your api-key' \
--header 'session-id: 7760a743-884b-4195-b781-892e72c7b0b6' \
--header 'device-type: android' \
--header 'document-type: idr' \
--header 'lang: vi' \
--form 'files=@"path-to-front.jpg"' \
--form 'files=@"path-to-back.jpg"'

2.5. Response

2.5.1. Mẫu response

• Thành công

{
    "errorCode": "0",
    "errorMessage": "",
    "data": [
        {
            "key": "ID",
            "name": "Số/ No",
            "value": "xxxxx",
            "score": "98.66",
            "locale": "vn"
        },
        {
            "key": "Name",
            "name": "Họ và tên",
            "value": "your name,
            "score": "99.71",
            "locale": "vn"
        },
        {
            "key": "Date of birth",
            "name": "Ngày sinh",
            "value": "dd/mm/yyyy",
            "score": "98.41",
            "locale": "vn"
        },
        {
            "key": "Sex",
            "name": "Giới tính",
            "value": "NAM",
            "score": "98.30",
            "locale": "vn"
        },
        {
            "key": "Nationality",
            "name": "Quốc tịch",
            "value": "VIỆT NAM",
            "score": "99.77",
            "locale": "vn"
        },
        {
            "key": "Home",
            "name": "Quê quán",
            "value": "X, Y NAM ĐỊNH",
            "score": "96.54",
            "locale": "vn"
        },
        {
            "key": "Address",
            "name": "Địa chỉ",
            "value": "X, Y NAM ĐỊNH",
            "score": "98.27",
            "locale": "vn"
        },
        {
            "key": "Expired Date",
            "name": "Ngày hết hạn",
            "value": "dd/mm/yyyy",
            "score": "98.93",
            "locale": "vn"
        },
        {
            "key": "Type",
            "name": "Loại",
            "value": "7",
            "score": "N/A",
            "locale": "vn"
        },
        {
            "key": "Province",
            "name": "Tỉnh/Thành Phố",
            "value": "NAM ĐỊNH",
            "score": "N/A",
            "locale": "vn"
        },
        {
            "key": "District",
            "name": "Quận/ Huyện",
            "value": "Y,
            "score": "N/A",
            "locale": "vn"
        },
        {
            "key": "Ward",
            "name": "Phường/Xã",
            "value": "X",
            "score": "N/A",
            "locale": "vn"
        },
        {
            "key": "Features",
            "name": "Đặc điểm nhận dạng",
            "value": "SẸO CHẤM ,
            "score": "99.78",
            "locale": "vn"
        },
        {
            "key": "Issue Date",
            "name": "Ngày cấp",
            "value": "dd/mm/yyyy",
            "score": "99.31",
            "locale": "vn"
        },
        {
            "key": "Issue Location",
            "name": "Nơi cấp",
            "value": "CỤC TRƯỞNG CỤC CẢNH SÁT QUẢN LÝ HÀNH CHÍNH VỀ TRẬT TỰ XÃ HỘI",
            "score": "95.40",
            "locale": "vn"
        }
    ],
    "total_data": []
}

2.5.2. Mô tả response

Tham số	Loại dữ liệu	Mô tả	Ghi chú
errorCode	Integer	Mã lỗi trả về từ server. errorCode = 0 nghĩa là yêu cầu thành công. Ngược lại, yêu cầu có lỗi.	Chi tiết có thể tìm thấy trong tài liệu mã lỗi
errorMessage	String	Thông báo lỗi của yêu cầu (nếu có). Ngôn ngữ của thông báo được đặt bởi tham số lang trong headers
data	Object	Chứa kết quả OCR

2.5.3. Mẫu response lỗi

• Phiên làm việc hết hạn: Trả về khi phiên không hợp lệ, ví dụ như: phiên chưa được đăng ký, phiên hết thời gian chờ, không khớp loại thiết bị, ...

{
    "errorCode": "403",
    "errorMessage": "Phiên làm việc đã hết hạn"
}

• Lỗi OCR

{
    "errorCode": "3",
    "errorMessage": "Không tìm thấy tài liệu đã chọn trong ảnh"
}

3. API kiểm tra liveness và so khớp khuôn mặt

3.1. Request Url

POST base_url/face/liveness

3.2. Request Headers

Tham số	Yêu cầu	Loại dữ liệu	Mô tả	Chú ý
session-id	Có	String	ID duy nhất của phiên eKYC nhận được từ bước khởi tạo phiên
api-key	Có	String	API key để sử dụng hệ thống FPT AI eKYC
auto	Không	string	Đặt giá trị là True khi gửi từ FPT SDK. Nếu không phải đặt False
device-type	Có	String	Thiết bị đang sử dụng, các giá trị cho phép bao gồm: android ios web-sdk
lang	Không	String	Ngôn ngữ sử dụng, các giá trị cho phép bao gồm: en vi	mặc định: en
sdk-version	Không	String	Phiên bản của FPT AI eKYC SDK. Nên sử dụng tham số này để đảm bảo hiệu quả khi sử dụng SDK

3.3. Request Body

FormData chứa ảnh hoặc video selfie sử dụng để kiểm tra.

Tham số	Yêu cầu	Loại dữ liệu	Mô tả
selfies	Không. Sử dụng selfies hoặc video	Array	Ảnh selfie được chụp để kiểm tra liveness và thực hiện so khớp khuôn mặt
video	Không. Sử dụng selfies hoặc video	File	Video selfie được quay để kiểm tra liveness và thực hiện so khớp khuôn mặt

3.4. Mẫu request

curl --location --request POST 'base_url/face/liveness' \
--header 'api-key: your-api-key' \
--header 'session-id: 7760a743-884b-4195-b781-892e72c7b0b6'
--header 'device-type: android' \
--header 'lang: vi' \
--form 'selfies=@"path-to-selfie-image"' \

3.5. Response

3.5.1. Mẫu response

• Thành công

{
    "code": "200",
    "message": "Kiểm tra thực thể sống thành công",
    "liveness": {
        "code": "200",
        "message": "liveness check successful",
        "is_live": "true",
        "spoof_prob": "N/A",
        "need_to_review": "N/A",
        "is_deepfake": "N/A",
        "deepfake_prob": "N/A",
        "warning": "N/A",
    },
    "face_match": {
        "code": "200",
        "message": "face matching successful",
        "isMatch": "true",
        "similarity": "95.84",
        "warning": "N/A"
    },
    "is_complete_session": false
}

3.5.2. Mô tả response

Tham số	Loại dữ liệu	Mô tả	Ghi chú
code	String	Mã trạng thái trả về của yêu cầu. Mã 200 nghĩa là yêu cầu thành công.	Chi tiết có thể được tìm thấy trong tài liệu mã lỗi
message	String	Thông báo lỗi của yêu cầu (nếu có). Ngôn ngữ của thông báo được đặt bởi tham số lang trong headers
liveness	Object	Kết quả kiểm tra liveness trả về
face_match	Object	Kết quả so khớp khuôn mặt trả về
is_complete_session	boolean	Xác định xem phiên đã hoàn thành hay chưa. Nếu False, người dùng có thể thử lại với xác minh khuôn mặt, nếu không, người dùng phải thử với một phiên khác

3.5.3. Mẫu response lỗi

• Khuôn mặt không khớp với giấy tờ: Trả về khi khuôn mặt trong ảnh selfie không khớp với khuôn mặt trong ảnh giấy tờ.

{
    "code": "303",
    "message": "Khuôn mặt không khớp với giấy tờ",
    "liveness": {
        "code": "200",
        "message": "liveness check successful",
        "is_live": "true",
        "spoof_prob": "N/A",
        "need_to_review": "N/A",
        "is_deepfake": "N/A",
        "deepfake_prob": "N/A",
        "warning": "N/A",
    },
    "face_match": {
        "code": "303",
        "message": "face is not matching with document",
        "isMatch": "false",
        "similarity": "5.84",
        "warning": "N/A"
    },
    "is_complete_session": false
}

• Có 2 khuôn mặt: Trả về khi hệ thống phát hiện nhiều hơn một khuôn mặt trong ảnh selfie.

{
    "code": "407",
    "message": "2 faces exist",
    "liveness": {
        "code": "200",
        "message": "liveness check successful",
        "is_live": "true",
        "spoof_prob": "N/A",
        "need_to_review": "N/A",
        "is_deepfake": "N/A",
        "deepfake_prob": "N/A",
        "warning": "N/A",
    },
    "face_match": {
        "code": "407",
        "message": "2 faces exist",
        "isMatch": "N/A",
        "similarity": "N/A",
        "warning": "N/A"
    },
    "is_complete_session": false
}

4. API kiểm tra data NFC

4.1. Request Url

POST base_url/check_chip

4.2. Request Headers

Tham số	Yêu cầu	Loại dữ liệu	Mô tả	Chú ý
session-id	Có	String	ID duy nhất của phiên nhận được từ request khởi tạo phiên
api-key	Có	String	API key của bạn để xác thực với hệ thống FPT AI eKYC
auto	Có	String	Đặt giá trị là True khi gọi từ FPT SDK. Ngược lại, đặt là False
device-type	Có	String	Thiết bị của bạn, các giá trị bao gồm: android ios
lang	Không	String	Ngôn ngữ sử dụng, các giá trị bao gồm: en: Tiếng Anh vi: Tiếng Việt	Mặc định: en
sdk-version	Không	String	Phiên bản của FPT AI eKYC SDK. Nên sử dụng tham số này để đảm bảo hiệu quả khi sử dụng SDK

4.3. Request Body

Parameter	Required	Type	Description
dg1	Có	String base64	Thông tin MRZ
dg2	Có	String base64	Ảnh chân dung
dg3	Có	String base64	Vân tay trái
dg4	Có	String base64	Vân tay phải
dg5	Có	String base64	Vùng nhớ chưa sử dụng
dg6	Có	String base64	Vùng nhớ chưa sử dụng
dg7	Có	String base64	Vùng nhớ chưa sử dụng
dg8	Có	String base64	Vùng nhớ chưa sử dụng
dg9	Có	String base64	Vùng nhớ chưa sử dụng
dg10	Có	String base64	Vùng nhớ chưa sử dụng
dg11	Có	String base64	Vùng nhớ chưa sử dụng
dg12	Có	String base64	Vùng nhớ chưa sử dụng
dg13	Có	String base64	Thông tin cơ bản của công dân
dg14	Có	String base64	Chứa các tùy chọn bảo mật cho các cơ chế bảo mật bổ sung
dg15	Có	String base64	Khóa công khai lưu trữ
dg16	Có	String base64	Vùng nhớ chưa sử dụng
sod	Có	String base64	Chữ ký số
challenge	Có	String base64
aAResult	Có	String base64	Thử thách ngẫu nhiên (mảng byte [8] gửi đến NFC Chip để thực hiện xác thực (Active Authentication)
eACCAResult	Có	String base64
com	Có	String base64
expired-date	Không	String	Ngày hết hạn
father	Không	String	Tên cha
features	Không	String	Đặc điểm
home	Không	String	Nguyên quán
id	Không	String	Số căn cước công dân
issue-date	Không	String	Ngày cấp
mother	Không	String	Tên mẹ
name	Không	String	Tên
nation	Không	String	Quốc gia
nationality	Không	String	Quốc tịch
prev-number	Không	String	Số CMND cũ
religion	Không	String	Tôn giáo
sex	Không	String	Giới tính
address	Không	String	Địa chỉ
face	Không	String base64	Ảnh chân dung
qrcode	Không	String	mã qrcode

4.4. Mẫu request

curl --location --request POST 'base-url/check_chip' \
--header 'api-key: your api key' \
--header 'session-id': 'your session id' \
--header 'device-type': 'android'\
--header 'lang': 'vi'\
--header 'Content-Type: application/json' \
--data '{
    "dg1": "...",
    "dg2": "...",
    "dg3": "...",
    ...
}'

4.5. Response

4.5.1. Mẫu response

• Thành công

{
    "errorCode": "0",
    "errorMessage": "",
    "valid": false,
    "verifyCode": 2,
    "verifyMessage": "Chưa xác thực thông tin C06",
    "rar_request_id": "N/A",
    "data": [
        {
            "key": "ID",
            "name": "Số/ No",
            "value": "xxxxxxxxxxx",
            "score": "N/A",
            "locale": "vn"
        },
        {
            "key": "PrevID",
            "name": "Số định danh trước kia",
            "value": " xxxxxxxxxxx ",
            "score": "N/A",
            "locale": "vn"
        },
        {
            "key": "Name",
            "name": "Họ & tên",
            "value": "Phạm Hoàng Tùng",
            "score": "N/A",
            "locale": "vn"
        },
        ...
    ]
}

4.5.2. Mô tả response

Tham số	Loại dữ liệu	Mô tả	Ghi chú
errorCode	String	Mã lỗi trả về từ server. errorCode = 0 nghĩa là yêu cầu thành công. Ngược lại, yêu cầu gặp lỗi.	Chi tiết có thể tìm thấy trong tài liệu mã lỗi
errorMessage	String	Thông báo lỗi của yêu cầu (nếu có). Ngôn ngữ của thông báo được đặt bởi tham số lang trong headers
valid	Boolean	True: Xác thực C06 thành công False: Chưa thực hiện xác thực C06
verifyCode	String	1: Xác thực thành công 0: Xác thực thất bại 2: Chưa xác thực
verifyMessage	String	Thông báo xác thực

5. API nhận thông tin QR Code

5.1. Request Url

POST base_url/qrcode

5.2. Request Headers

Parameter	Required	Data type	Description	Note
session-id	Có	String	ID duy nhất của phiên nhận được từ request khởi tạo phiên
api-key	Có	String	API key của bạn để xác thực với hệ thống FPT AI eKYC
device-type	Có	String	Thiết bị của bạn, các giá trị bao gồm: android ios
lang	Không	String	Ngôn ngữ sử dụng, các giá trị bao gồm: en: Tiếng Anh vi: Tiếng Việt	Mặc định: en
sdk-version	Không	String	Phiên bản của FPT AI eKYC SDK

5.3. Request Body

Parameter	Required	Type	Description
qrcode	Có	String	Thông tin trong QR code

5.4. Mẫu request

curl --location --request POST 'base_url/qrcode' \
--header 'Content-Type: application/json' \
--header 'api-key: your api-key' \
--header 'session-id: 7760a743-884b-4195-b781-892e72c7b0b6' \
--header 'device-type: android' \
--header 'lang: vi' \
--data-raw '{
"qrcode": "0461990xxxxx|xxxxxxx|Nguyễn Văn A|060619.....
}'

5.5. Response

5.5.1. Mẫu response

• Thành công

{
    "errorCode": "0",
    "errorMessage": ""
}

• Thất bại

  • Phiên làm việc hết hạn: Trả về khi phiên không hợp lệ, ví dụ như: phiên chưa được đăng ký, phiên hết thời gian chờ, không khớp loại thiết bị, ...

    {
        "errorCode": "403",
        "errorMessage": "Phiên làm việc đã hết hạn"
    }

  • Lỗi QRcode:

    {
        "errorCode": "QR01",
        "errorMessage": "Dữ liệu trong mã QR không khớp"
    }

5.5.2. Mô tả response

Tham số	Loại dữ liệu	Mô tả	Ghi chú
errorCode	String	Mã lỗi trả về từ server. errorCode = 0 nghĩa là request thành công. Ngược lại, request gặp lỗi.
errorMessage	String	Thông báo lỗi của request (nếu có). Ngôn ngữ của thông báo được đặt bởi tham số lang trong headers

6. API Logging & Tracing

API này được thiết kế để phục vụ cho việc ghi log và truy vết exception ở phía SDK.
Thông thường, SDK không gửi bất kỳ dữ liệu nào. Việc ghi log chỉ được kích hoạt thông qua cấu hình ở Portal.

• Trong quá trình gọi API init_session, server có thể trả về một flag:

  { "enable_tracing": true }

• Nếu enable_tracing = true, SDK sẽ bắt đầu gửi thông tin log và exception qua API này.

• Nếu enable_tracing = false (hoặc không có flag này), SDK sẽ không được phép gửi thông tin log và exception.

Cơ chế này đảm bảo rằng việc ghi log chỉ được kích hoạt trong các trường hợp debug hoặc error, giúp lập trình viên thu thập thông tin truy vết chi tiết mà không gây tốn tài nguyên trong quá trình vận hành thông thường.

6.1. Request Url

POST base_url/logging/tracing

6.2. Request Headers

Tham số	Yêu cầu	Loại dữ liệu	Mô tả	Chú ý
session-id	Không	String	ID duy nhất của phiên eKYC nhận được từ bước khởi tạo phiên
api-key	Có	String	API key để sử dụng hệ thống FPT AI eKYC
device-type	Không	String	Thiết bị đang sử dụng, các giá trị cho phép bao gồm: android ios web-sdk Cần thêm các tham số này nếu như thông tin log được gửi từ nhiều client khác nhau
lang	No	String	Ngôn ngữ sử dụng, các giá trị cho phép bao gồm: en vi Cần thêm các tham số này nếu như thông tin log được gửi từ nhiều client khác nhau	Mặc định: en
sdk-version	No	String	Version of FPT AI eKYC SDK. Cần thêm các tham số này nếu như thông tin log được gửi từ nhiều client khác nhau
Content-Type	Yes	String	Xác định loại nội dung của request body	Bắt buộc là application/json

6.3. Request Body

Tham số	Loại dữ liệu	Yêu cầu	Mô tả
event	string	Không	Tên hoặc hành động của sự kiện (ví dụ: face.liveness.start).
level	string	Không	Mức độ log debug, info, warn, error, fatal.
message	string	Không	Thông điệp mô tả
timestamp	string (ISO 8601)	Không	Thời điểm xảy ra sự kiện phía client. Server sẽ tự gán giá trị nếu không có.
duration_ms	number	Không	Thời gian thực hiện cho các tác vụ có thời gian đo (miliseconds)
attributes	object	Không	Tập các cặp key-value tùy chỉnh(ví dụ: device info, user context).
session_meta	object	Không	Metadata bổ sung của phiên eKYC (ví dụ:{ sdk: "android", version: "1.2.3" }).
trace_id	string	Không	Mã định danh liên kết cho việc truy vết
span_id	string	Không	Mã định danh của span trong trace (nếu có).
exception	object	Không	Chi tiết exception/error (Chi tiết bên dưới).

Exception object

Tham số	Loại dữ liệu	Yêu cầu	Mô tả
type	string	Không	Loại Exception hoặc tên class (ví dụ:NullPointerException).
message	string	Không	Thông điệp mô tả
stacktrace	string	Không	Thông tin stack trace
file	string	Không	Tên source file nơi xảy ra lỗi
line	number	Không	Số dòng trong file nơi xảy ra lỗi
code	string	Không	Mã lỗi (nếu có)
handled	boolean	Không	true nếu exception đã được truy vết/xử lý, false nếu chưa.
detail	object	Không	Free-form JSON object chứa thông tin bổ sung (nếu SDK có thể gửi thêm bất kỳ dữ liệu nào).

6.4. Request Sample

curl --location --request POST '<base_url>/logging/tracing' \
--header 'api-key: your-api-key' \
--header 'session-id: 7760a743-884b-4195-b781-892e72c7b0b6' \
--header 'Content-Type: application/json' \
--data '{
  "event": "face.match",
  "level": "error",
  "message": "Face match failed on SDK",
  "timestamp": "2025-10-03T04:15:23.412Z",
  "attributes": {
    "device_type": "android",
    "os_version": "14",
    "sdk_version": "2.4.0"
  },
  "exception": {
    "type": "IllegalArgumentException",
    "message": "Invalid image format",
    "stacktrace": "com.fpt.sdk.FaceMatch.process(FaceMatch.java:102)\ncom.fpt.sdk.MainActivity.onResult(MainActivity.kt:45)",
    "file": "FaceMatch.java",
    "line": 102,
    "handled": true,
    "detail": {}
  }
}'

6.5. Response

6.5.1. Response Sample

• Succeeded

http_code = 200

{
    "code": "200",
    "message": "Success"
}

• Failed

http_code != 200